home *** CD-ROM | disk | FTP | other *** search
/ BCI NET / BCI NET Dec 94.iso / archives / programming / blitzbasic / riblitzlibs.lha / riblitzlibs / zonejoy / ZoneJoy_Library.DOC < prev    next >
Encoding:
Text File  |  1994-06-20  |  8.2 KB  |  250 lines
  1. Reflective Images Zone-Joystick Library v1.2
  2. ============================================
  3.  
  4. By Stephen McNamara, original Joy Library by Steve Matty
  5. (c)1994 Reflective Images
  6.  
  7. This version: 1.2
  8.           18/6/94
  9.  
  10. This library contains commands for setting up zones and testing the status
  11. of the joysticks attached to the Amiga.
  12.  
  13. New additions to this library allow you to have multiple lists of zones
  14. (refered to as zonetables in this doc).  To maintain compatibility with
  15. older versions of the library, zonetable 0 is equivalent of the original
  16. list of zones used in the library.  You cannot adjust the size of zonetable
  17. 0 (its size is 256 zones), nor can you delete it.  The new zonetables can
  18. be from 1 to 65536 in size, there are 16 available zonetable numbers.
  19.  
  20. All commands that change or test zones will work on the last zonetable that
  21. was selected with the command UseZoneTable.  The default table is number 0.
  22.  
  23. Command list:
  24.             ZoneInit [zone_num]|[start_zone,end_zone]
  25.             Setzone zone#,x1,y1,radius
  26.             Setzone zone#,x1,y1,x2,y2
  27.             a.w=Zone(x,y)
  28.             a.w=ZoneTest(start_zone[,end_zone],x,y)
  29.             ad.l=ZoneTable
  30.         (*)    size.l=ZoneTableSize (table#)
  31.         (*)    UseZoneTable table#
  32.         (*)    NewZoneTable table#,size
  33.         (*)    FreeZoneTable table#
  34.  
  35.             jf.b=JFire(joy#)
  36.             jv.b=JVert(joy#)
  37.             jh.b=JHoriz(joy#)
  38.             af.b=AllFire [bit_pattern]
  39.  
  40. (*)=new for this version of the Zone-Joystick library.
  41.  
  42.  
  43. Statement: ZoneInit
  44. ------------------------------------------------------------------------
  45. Modes  : Amiga/Blitz
  46. Syntax : ZoneInit [zone_num]|[start_zone,end_zone]
  47.  
  48.   This command is used to clear any zones currently set.  The optional
  49.   parameters allow you to select either a single zone or a range of zones
  50.   to reset.
  51.  
  52.  
  53. Statement/Function: Setzone
  54. ------------------------------------------------------------------------
  55. Modes  : Amiga/Blitz
  56. Syntax : Setzone zone#,x1,y1,radius
  57.          Setzone zone#,x1,y1,x2,y2
  58.  
  59.   This command lets you set up zones for testing.  The first version is
  60.   used when you want to set up a circular zone and the second when you want
  61.   a rectangular one.  With rectangular zones, x1,y1 should be the top left
  62.   corner of the rectangle and x2,y2 should be the bottom left.
  63.  
  64.   If used as a function, this command returns TRUE or FALSE to say whether
  65.   or not the change was made.
  66.  
  67.   Note: The max zone number for zonetable 0 is 255.
  68.     A zone number outside the range of the current table will
  69.         cause this command to abort.
  70.         Zones can be defined in any order.
  71.         Circular zones are used in exactly the same way as rectangular
  72.         ones.
  73.  
  74.  
  75. Function: Zone
  76. ------------------------------------------------------------------------
  77. Modes  : Amiga/Blitz
  78. Syntax : a.w=Zone(x,y)
  79.  
  80.   This command takes the co-ordinates x,y and checks to see if they are
  81.   inside any of the defined zones.  The zones are searched in order,
  82.   starting at 0 and going through to the size of the zonetable-1.  This
  83.   command will return the first zone that the co-ordinates were found to
  84.   be inside, you should note that both types of zones are tested
  85.   (rectangular and circular).
  86.  
  87.   This command returns either -1 for not inside a zone or the zone number.
  88.  
  89.  
  90. Function: ZoneTest
  91. ------------------------------------------------------------------------
  92. Modes  : Amiga/Blitz
  93. Syntax : a.w=ZoneTest(start_num[,end_num],x,y)
  94.  
  95.   This command is the same as the Zone command except that it allows you
  96.   to select either one individual zone to test or a range of zones.  You
  97.   should, though, ensure that end_num if greater than start_num.
  98.  
  99.   This command returns either -1 for not inside a zone or the zone number.
  100.  
  101.  
  102. Function: ZoneTable
  103. ------------------------------------------------------------------------
  104. Modes  : Amiga/Blitz
  105. Syntax : ad.l=ZoneTable
  106.  
  107.   This function returns the address in memory of the zone information
  108.   storage area for the current zonetable. The zones are stored one after
  109.   the other, with each zone taking up 8 words (16 bytes) in the data area,
  110.   making a total size of 2048 bytes.  They are stored in the following way:
  111.  
  112.         Rectangular:      +0: x1
  113.                 +2: y1
  114.                 +4: x2
  115.                 +6: y2
  116.  
  117.         Circular:    +0: x1
  118.                 +2: y1
  119.                 +4: radius of zone
  120.                 +6: -1 <-- this is set to show that the
  121.                             zone is circular.
  122.  
  123.         Undefined zone:    +0: -1
  124.                 +2: -1
  125.                 +4: -1
  126.                 +6: -1
  127.  
  128.   The first longword (4 bytes) of the zonetable is used to hold the size,
  129. in zones, of the table (thus the true size of the zonetable is 4+number of
  130. zones*8).
  131.  
  132.  
  133. Function: ZoneTableSize
  134. ------------------------------------------------------------------------
  135. Modes  : Amiga/Blitz
  136. Syntax : size.l=ZoneTableSize
  137.  
  138.   This function returns the size, in zones, of the current zonetable.  It
  139. is equivalent of doing: size.l=peek.l(ZoneTable).
  140.  
  141.  
  142. Statement/Function: NewZoneTable
  143. ------------------------------------------------------------------------
  144. Modes  : Amiga/Blitz
  145. Syntax : NewZoneTable table#,size
  146.  
  147.   This command will attempt to allocate a new zonetable with the given
  148. table number.  If the table already exists it will be deleted.  The maximum
  149. size for a zonetable is 65536 zones.  If used as a function, this command
  150. will return FALSE for failure or TRUE for success.  You should note that
  151. all zones are automatically reset in the new table and that creating a
  152. table does not make it the current table, this must be done with
  153. UseZoneTable.
  154.   Valid zonetable numbers range from 0 to 15.
  155.  
  156.   IMPORTANT NOTE: you cannot define the size of zonetable 0.  You cannot
  157. use this command to alter it in any way.
  158.  
  159.  
  160. Statement/Function: UseZoneTable
  161. ------------------------------------------------------------------------
  162. Modes  : Amiga/Blitz
  163. Syntax : UseZoneTable table#
  164.  
  165.   This command is used to change the current zonetable to the selected one.
  166. If used as a function, it will return TRUE for success or FALSE for
  167. failure.
  168.   Valid zonetable numbers range from 0 to 15.
  169.  
  170.  
  171. Statement/Function: FreeZoneTable
  172. ------------------------------------------------------------------------
  173. Modes  : Amiga/Blitz
  174. Syntax : FreeZoneTable table#
  175.  
  176.   This command is used to free a zonetable from memory.  If used as a
  177. function, it will return TRUE or FALSE.  When successfully called, this
  178. command will free the zonetable and change the currently used zonetable to
  179. table number 0.
  180.   Valid zonetable numbers range from 0 to 15.
  181.  
  182.   IMPORTANT NOTE: you cannot free zone table 0.
  183.  
  184.  
  185. Function: JFire
  186. ------------------------------------------------------------------------
  187. Modes  : Amiga/Blitz
  188. Syntax : jf.b=JFire(joy#)
  189.  
  190.   This command tests the fire button status of the joystick joy#, where
  191.   joy# is between 1 and 4.  You should note that, as with all the joystick
  192.   commmands, joy#=1 refers to the Amiga's joystick port, joy#=2 refers to
  193.   the mouse port, and joy#=3 or joy#=4 refer to the four player adapter
  194.   ports.
  195.  
  196.   This command returns 0 for fire button not pressed or -1 for pressed
  197.  
  198.  
  199. Function: JHoriz
  200. ------------------------------------------------------------------------
  201. Modes  : Amiga/Blitz
  202. Syntax : jh.b=JHoriz(joy#)
  203.  
  204.   This command is used to test the horizontal direction of the selected
  205.   joystick.  It returns:
  206.  
  207.         0: No horizontal direction
  208.              -1: Joystick left
  209.             1: Joystick right
  210.  
  211.  
  212. Function: JVert
  213. ------------------------------------------------------------------------
  214. Modes  : Amiga/Blitz
  215. Syntax : jv.b=JVert(joy#)
  216.  
  217.   This command is used to test the vertical direction of the selected
  218.   joystick.  It returns:
  219.  
  220.         0: No vertical direction
  221.              -1: Joystick up
  222.             1: Joystick down
  223.  
  224.  
  225. Function: AllFire
  226. ------------------------------------------------------------------------
  227. Modes  : Amiga/Blitz
  228. Syntax : af.b=AllFire [(bit_pattern)]
  229.  
  230.   This command is used to test the fire button status of all four
  231.   joysticks.  It returns a byte with the first four bits giving the
  232.   joystick status, false=fire button not pressed, true=fire button pressed.
  233.   The following bits belong to joysticks:
  234.  
  235.         bit 0: joystick 1 (joystick port)
  236.         bit 1: joystick 2 (mouse port)
  237.         bit 2: joystick 3 (four player adaptor)
  238.         bit 3: joystick 4 (four player adaptor)
  239.  
  240.   The optional bit pattern can be used to restrict the testing of the fire
  241.   buttons.  If a bit in the pattern is clear (false) then the joystick it
  242.   belongs to will not have its fire button tested,
  243.  
  244.       e.g. AllFire (%0011) will test joysticks 1 and 2 and return the
  245.              result.  It will return false for joysticks 3 and 4.
  246.  
  247.  
  248.  
  249. >>END  
  250.